Thinking about how --input-tileset interacts with the -o output made me realize: what happens if you don't also pass -u? When you do pass -u, the output image can be understood as a tileset, needing a tilemap to get the output back, But when you don't pass -u, the output image can be understood as a copy of the input image, just encoded as 2BPP instead of PNG. So, if you pass an input tileset, what gets output for these various cases:

1. Input tile A occurs once in input image
2. Input tile B occurs three times in input image
3. Input tile C does not occur in input image
4. Input tiles D and E are identical, and occur {zero / one / more} times in input image
5. Input tile F is fully alpha-transparent

(We'll also have to consider "what if an input tile is solid #FF00FF and you pass --background #FF00FF".)

Furthermore, regardless of how we handle the above concerns re: not passing -u, we'll need to update the -u docs. It says:

Note that if this option is enabled, no guarantee is made on the order in which tiles are output; while it should be consistent across identical runs of a given rgbgfx release, the same is not true for different releases.

But in fact --input-tileset is making a guarantee ("these tiles will be first"). Do/should we also guarantee that those input tiles will have some specific order among themselves? (Presumably "the same order as they came in, top to bottom left to right, minus any deduplicated ones"?)

Thinking about how --input-tileset interacts with the -o output made me realize: what happens if you don't also pass -u? When you do pass -u, the output image can be understood as a tileset, needing a tilemap to get the output back, But when you don't pass -u, the output image can be understood as a copy of the input image, just encoded as 2BPP instead of PNG. So, if you pass an input tileset, what gets output for these various cases:

1. Input tile A occurs once in input image

2. Input tile B occurs three times in input image

3. Input tile C does not occur in input image

4. Input tiles D and E are identical, and occur {zero / one / more} times in input image

5. Input tile F is fully alpha-transparent

IMO, it's simple: we generate tile data appending it to the input tileset, then run the deduplication pass if requested. This preserves all guarantees, and is a simple yet reasonable model. (Note that there is an explicit check that the deduplication pass does not dedup any of the input tileset's tiles, which would violate the assumption that all input tiles are present as-is in the output.)

The answer to all the following is “emitted once” with -u, obviously, but without:

1. It's emitted twice.
2. It's emitted all four times.
3. It's emitted once.
4. They're emitted once each.
5. Made moot by the point below.

(We'll also have to consider "what if an input tile is solid #FF00FF and you pass --background #FF00FF".)

We don't, because deduplication is performed on tile data, so colours are already out of the picture by then. (This is why -c is strongly advised for multi-palette images).

But in fact --input-tileset is making a guarantee ("these tiles will be first"). Do/should we also guarantee that those input tiles will have some specific order among themselves? (Presumably "the same order as they came in, top to bottom left to right, minus any deduplicated ones"?)

We can simply mention that these guarantees are upheld regardless of any dedup flags, or update all four of those flags' descriptions to mention that they only apply to generated tiles but that they are still compared against input tiles. My vote goes for the former.

And, yes, the intent is to basically guarantee that rgbgfx -i in.2bpp img.png -o out.2bpp; truncate -s $(wc -c <in.2bpp) out.2bpp; cmp in.2bpp out.2bpp always returns true. I guess the docs aren't making the full promise, but I'm not sure as to how to word it.

Great! That sounds simple, consistent, and predictable. And people almost certainly want -u when using a tileset anyway, so it doesn't have to somehow be useful too. :P

the intent is to basically guarantee that rgbgfx -i in.2bpp img.png -o out.2bpp; truncate -s $(wc -c <in.2bpp) out.2bpp; cmp in.2bpp out.2bpp always returns true. I guess the docs aren't making the full promise, but I'm not sure as to how to word it.

Let's get the rest working first and then come back to how to word that; I may have suggestions in a subsequent review.

In theory we could reject -i without -u, as

rgbgfx a.png -o a.2bpp
rgbgfx b.png -o b.2bpp -i a.2bpp

is in fact equivalent to

rgbgfx a.png -o a.2bpp
rgbgfx b.png -o tmp.2bpp
cat a.2bpp tmp.2bpp >b.2bpp

...so we could reserve that combination for later to be more useful behaviour. What do you think?

Yes, disallowing -i without -u (at least in its initial release) sounds better.